<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python documentation Index' />
<link rel="first" href="lib.html" title='Python library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="module-base64.html" />
<link rel="prev" href="module-multifile.html" />
<link rel="parent" href="netdata.html" />
<link rel="next" href="message-objects.html" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name='aesop' content='information' />
<title>7.10 rfc822 -- Parse RFC 2822 mail headers</title>
</head>
<body>
<div class="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="7.9.2 multifile Example"
  href="multifile-example.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="7. internet Data Handling"
  href="netdata.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="7.10.1 message Objects"
  href="message-objects.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="multifile-example.html">7.9.2 MultiFile Example</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="netdata.html">7. Internet Data Handling</a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="message-objects.html">7.10.1 Message Objects</a>
</div>
<hr /></div>
</div>
<!--End of Navigation Panel-->

<h1><a name="SECTION0091000000000000000000">
7.10 <tt class="module">rfc822</tt> --
         Parse RFC 2822 mail headers</a>
</h1>

<p>
<a name="module-rfc822"></a>

<p>
<div class="versionnote"><b>Deprecated since release 2.3.</b>
The <tt class="module"><a href="module-email.html">email</a></tt> package should be used in
                 preference to the <tt class="module">rfc822</tt> module.  This
                 module is present only to maintain backward
                 compatibility.</div><p></p>

<p>
This module defines a class, <tt class="class">Message</tt>, which represents an
``email message'' as defined by the Internet standard
<a class="rfc" id='rfcref-99725' xml:id='rfcref-99725'
href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>.<a name="tex2html82"
  href="#foot25768"><sup>7.6</sup></a>  Such messages
consist of a collection of message headers, and a message body.  This
module also defines a helper class
<tt class="class">AddressList</tt> for parsing <a class="rfc" id='rfcref-99727' xml:id='rfcref-99727'
href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> addresses.  Please refer to
the RFC for information on the specific syntax of <a class="rfc" id='rfcref-99729' xml:id='rfcref-99729'
href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> messages.

<p>
The <tt class="module"><a href="module-mailbox.html">mailbox</a></tt><a id='l2h-1570' xml:id='l2h-1570'></a> module provides classes 
to read mailboxes produced by various end-user mail programs.

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-1561' xml:id='l2h-1561' class="class">Message</tt></b>(</nobr></td>
  <td><var>file</var><big>[</big><var>, seekable</var><big>]</big><var></var>)</td></tr></table></dt>
<dd>
A <tt class="class">Message</tt> instance is instantiated with an input object as
parameter.  Message relies only on the input object having a
<tt class="method">readline()</tt> method; in particular, ordinary file objects
qualify.  Instantiation reads headers from the input object up to a
delimiter line (normally a blank line) and stores them in the
instance.  The message body, following the headers, is not consumed.

<p>
This class can work with any input object that supports a
<tt class="method">readline()</tt> method.  If the input object has seek and tell
capability, the <tt class="method">rewindbody()</tt> method will work; also, illegal
lines will be pushed back onto the input stream.  If the input object
lacks seek but has an <tt class="method">unread()</tt> method that can push back a
line of input, <tt class="class">Message</tt> will use that to push back illegal
lines.  Thus this class can be used to parse messages coming from a
buffered stream.

<p>
The optional <var>seekable</var> argument is provided as a workaround for
certain stdio libraries in which <tt class="cfunction">tell()</tt> discards buffered
data before discovering that the <tt class="cfunction">lseek()</tt> system call
doesn't work.  For maximum portability, you should set the seekable
argument to zero to prevent that initial <tt class="method">tell()</tt> when passing
in an unseekable object such as a file object created from a socket
object.

<p>
Input lines as read from the file may either be terminated by CR-LF or
by a single linefeed; a terminating CR-LF is replaced by a single
linefeed before the line is stored.

<p>
All header matching is done independent of upper or lower case;
e.g. <code><var>m</var>['From']</code>, <code><var>m</var>['from']</code> and
<code><var>m</var>['FROM']</code> all yield the same result.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-1562' xml:id='l2h-1562' class="class">AddressList</tt></b>(</nobr></td>
  <td><var>field</var>)</td></tr></table></dt>
<dd>
You may instantiate the <tt class="class">AddressList</tt> helper class using a single
string parameter, a comma-separated list of <a class="rfc" id='rfcref-99732' xml:id='rfcref-99732'
href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> addresses to be
parsed.  (The parameter <code>None</code> yields an empty list.)
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1563' xml:id='l2h-1563' class="function">quote</tt></b>(</nobr></td>
  <td><var>str</var>)</td></tr></table></dt>
<dd>
Return a new string with backslashes in <var>str</var> replaced by two
backslashes and double quotes replaced by backslash-double quote.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1564' xml:id='l2h-1564' class="function">unquote</tt></b>(</nobr></td>
  <td><var>str</var>)</td></tr></table></dt>
<dd>
Return a new string which is an <em>unquoted</em> version of <var>str</var>.
If <var>str</var> ends and begins with double quotes, they are stripped
off.  Likewise if <var>str</var> ends and begins with angle brackets, they
are stripped off.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1565' xml:id='l2h-1565' class="function">parseaddr</tt></b>(</nobr></td>
  <td><var>address</var>)</td></tr></table></dt>
<dd>
Parse <var>address</var>, which should be the value of some
address-containing field such as <span class="mailheader">To:</span> or <span class="mailheader">Cc:</span>,
into its constituent ``realname'' and ``email address'' parts.
Returns a tuple of that information, unless the parse fails, in which
case a 2-tuple <code>(None, None)</code> is returned.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1566' xml:id='l2h-1566' class="function">dump_address_pair</tt></b>(</nobr></td>
  <td><var>pair</var>)</td></tr></table></dt>
<dd>
The inverse of <tt class="method">parseaddr()</tt>, this takes a 2-tuple of the form
<code>(<var>realname</var>, <var>email_address</var>)</code> and returns the string
value suitable for a <span class="mailheader">To:</span> or <span class="mailheader">Cc:</span> header.  If
the first element of <var>pair</var> is false, then the second element is
returned unmodified.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1567' xml:id='l2h-1567' class="function">parsedate</tt></b>(</nobr></td>
  <td><var>date</var>)</td></tr></table></dt>
<dd>
Attempts to parse a date according to the rules in <a class="rfc" id='rfcref-99734' xml:id='rfcref-99734'
href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>.
however, some mailers don't follow that format as specified, so
<tt class="function">parsedate()</tt> tries to guess correctly in such cases. 
<var>date</var> is a string containing an <a class="rfc" id='rfcref-99736' xml:id='rfcref-99736'
href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> date, such as 
<code>'Mon, 20 Nov 1995 19:12:08 -0500'</code>.  If it succeeds in parsing
the date, <tt class="function">parsedate()</tt> returns a 9-tuple that can be passed
directly to <tt class="function">time.mktime()</tt>; otherwise <code>None</code> will be
returned.  Note that fields 6, 7, and 8 of the result tuple are not
usable.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1568' xml:id='l2h-1568' class="function">parsedate_tz</tt></b>(</nobr></td>
  <td><var>date</var>)</td></tr></table></dt>
<dd>
Performs the same function as <tt class="function">parsedate()</tt>, but returns
either <code>None</code> or a 10-tuple; the first 9 elements make up a tuple
that can be passed directly to <tt class="function">time.mktime()</tt>, and the tenth
is the offset of the date's timezone from UTC (which is the official
term for Greenwich Mean Time).  (Note that the sign of the timezone
offset is the opposite of the sign of the <code>time.timezone</code>
variable for the same timezone; the latter variable follows the
POSIX standard while this module follows <a class="rfc" id='rfcref-99738' xml:id='rfcref-99738'
href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>.)  If the input
string has no timezone, the last element of the tuple returned is
<code>None</code>.  Note that fields 6, 7, and 8 of the result tuple are not
usable.
</dl>

<p>
<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
  <td><nobr><b><tt id='l2h-1569' xml:id='l2h-1569' class="function">mktime_tz</tt></b>(</nobr></td>
  <td><var>tuple</var>)</td></tr></table></dt>
<dd>
Turn a 10-tuple as returned by <tt class="function">parsedate_tz()</tt> into a UTC
timestamp.  If the timezone item in the tuple is <code>None</code>, assume
local time.  Minor deficiency: this first interprets the first 8
elements as a local time and then compensates for the timezone
difference; this may yield a slight error around daylight savings time
switch dates.  Not enough to worry about for common use.
</dl>

<p>
<div class="seealso">
  <p class="heading">See Also:</p>

  <dl compact="compact" class="seemodule">
    <dt>Module <b><tt class="module"><a href="module-email.html">email</a></tt>:</b>
    <dd>Comprehensive email handling package; supersedes
                    the <tt class="module">rfc822</tt> module.
  </dl>
  <dl compact="compact" class="seemodule">
    <dt>Module <b><tt class="module"><a href="module-mailbox.html">mailbox</a></tt>:</b>
    <dd>Classes to read various mailbox formats produced 
                      by end-user mail programs.
  </dl>
  <dl compact="compact" class="seemodule">
    <dt>Module <b><tt class="module"><a href="module-mimetools.html">mimetools</a></tt>:</b>
    <dd>Subclass of <tt class="class">rfc822.Message</tt> that
                        handles MIME encoded messages.
  </dl> 
</div>

<p>
<br><hr><h4>Footnotes</h4>
<dl>
<dt><a name="foot25768">...2822.</a><A
 href="module-rfc822.html#tex2html82"><sup>7.6</sup></a></dt>
<dd>This module originally conformed to <a class="rfc" id='rfcref-99706' xml:id='rfcref-99706'
href="http://www.faqs.org/rfcs/rfc822.html">RFC 822</a>,
hence the name.  Since then, <a class="rfc" id='rfcref-99708' xml:id='rfcref-99708'
href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a> has been released as an
update to <a class="rfc" id='rfcref-99710' xml:id='rfcref-99710'
href="http://www.faqs.org/rfcs/rfc822.html">RFC 822</a>.  This module should be considered
<a class="rfc" id='rfcref-99712' xml:id='rfcref-99712'
href="http://www.faqs.org/rfcs/rfc2822.html">RFC 2822</a>-conformant, especially in cases where the
syntax or semantics have changed since <a class="rfc" id='rfcref-99714' xml:id='rfcref-99714'
href="http://www.faqs.org/rfcs/rfc822.html">RFC 822</a>.

</dd>
</dl>
<p><br /></p><hr class='online-navigation' />
<div class='online-navigation'>
<!--Table of Child-Links-->
<a name="CHILD_LINKS"><strong>Subsections</strong></a>

<ul class="ChildLinks">
<li><a href="message-objects.html">7.10.1 Message Objects</a>
<li><a href="addresslist-objects.html">7.10.2 AddressList Objects</a>
</ul>
<!--End of Table of Child-Links-->
</div>

<div class="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="7.9.2 multifile Example"
  href="multifile-example.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="7. internet Data Handling"
  href="netdata.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="7.10.1 message Objects"
  href="message-objects.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="multifile-example.html">7.9.2 MultiFile Example</a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="netdata.html">7. Internet Data Handling</a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="message-objects.html">7.10.1 Message Objects</a>
</div>
</div>
<hr />
<span class="release-info">Release 2.5.1, documentation updated on 18th April, 2007.</span>
</div>
<!--End of Navigation Panel-->
<address>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</address>
</body>
</html>
